.TH std::basic_string::copy 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string::copy \- std::basic_string::copy

.SH Synopsis
   size_type copy( CharT* dest, size_type count, size_type pos  (constexpr since C++20)
   = 0 ) const;

   Copies a substring [pos, pos + count) to character string pointed to by dest. If the
   requested substring lasts past the end of the string, or if count == npos, the
   copied substring is [pos, size()).

   The resulting character string is not null-terminated.

.SH Parameters

   dest  - pointer to the destination character string
   count - length of the substring
   pos   - position of the first character to include

.SH Return value

   Number of characters copied.

.SH Exceptions

   std::out_of_range if pos > size().

   If an exception is thrown for any reason, this function has no effect (strong
   exception safety guarantee).

.SH Complexity

   Linear in count.

.SH Example


// Run this code

 #include <iostream>
 #include <string>

 int main()
 {
     std::string foo("WINE");

     // brace-initialization initializes all characters to 0,
     // providing a null-terminator
     char bar[4]{};

     // do not copy the last char, to guarantee null-termination
     foo.copy(bar, sizeof bar - 1);

     std::cout << bar << '\\n'; // requires bar to be null-terminated
 }

.SH Output:

 WIN

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to        Behavior as published              Correct behavior
   LWG 847 C++98      there was no exception safety       added strong exception safety
                      guarantee                           guarantee

.SH See also

   substr  returns a substring
           \fI(public member function)\fP
   copy    copies characters
           \fI(public member function of std::basic_string_view<CharT,Traits>)\fP
   copy    copies a range of elements to a new location
   copy_if \fI(function template)\fP
   \fI(C++11)\fP
   memcpy  copies one buffer to another
           \fI(function)\fP
